====== API for Data Retrieval ======

SoSci Survey offers an API for data retrieval. Navigate to **Collected Data** -> **API for Data Retrieval** to create an API link.

API formats include:

  * JSON data
  * View single questionnaire \\ This function may be used to allow third parties to view single questionnairess.

Before you create the API link ('+' symbol in the top right corner), you may choose which records (e.g., interview and/or pretest data, interview date, etc.) may be retrieved (and may not be retrieved). 

===== JSON data retrieval =====

By default, the API link retrieves all collected data (according to the retrieval criteria defined for the API link).


==== Export ====

The JSON file contains the following attributes.

  * ''metadata''\\ Metadata, for example data retrieval timestamp, retrieval criteria (''filter'').
  * ''errors''\\ Potential retrieval errors, for example a non-existing variable. Only exists in the file if any errors occurred.
  * ''data''\\ The dataset. Each case is again a sub-attribute with the key ''C'' + case number.
    * ''C213''\\ Single cases (rows in the dataset) are objects with variable names as keys and their values stored as the object value. If there is no value for a variable (e.g., question not shown to participant, no answer), the variable is __not__ listed.
  * ''variables''\\ Additional information about the variables and their labels. Only exists in the file if the parameters "infoVariables", "infoValues" and/or "infoQuestionText" were added to the API call).

<code json>
{
  "metadata": {
    "project": "z2018",
    "datetime": "2018-08-01 22:35:18",
    "filter": [
      "Only selected cases: CASE 120, 121"
    ],
    "language": "ger"
  },
  "data": {
    "C120": {
      "CASE": 120,
      "SERIAL": "H3PVKWVM6H",
      "QUESTNNR": "short",
      "MODE": "interview",
      "STARTED": "2018-03-30 21:16:33",
      "T109_01": 4,
      "FINISHED": 1,
      "Q_VIEWER": 0,
      "LASTPAGE": 2,
      "MAXPAGE": 2
    },
    "C121": {
      "CASE": 121,
      "SERIAL": "LSFK1ZX25B",
      "QUESTNNR": "short",
      "MODE": "interview",
      "STARTED": "2018-03-30 21:16:55",
      "T109_01": 2,
      "FINISHED": 1,
      "Q_VIEWER": 0,
      "LASTPAGE": 2,
      "MAXPAGE": 2
    }
  }
}
</code>


==== Parameter ====

All parameters are optional. If no parameters are added to the API link, all cases (as defined in the retrieval criteria) will be retrieved.

  * ''cases'' -- Cases (CASE) to be retrieved.
    * You may add ranges (1-100) or single values. Separate multiple values by commas, for example ''1,2,5,10-20''.
    * The last (!) value may be a range without an endpoint, for example ''101-'' to retrieve all cases starting from CASE 101.
    * **Note:** If cases are specified that were restricted during the API link creation, only non-restricted cases are retrieved. For example, if the API link is limited to cases ''1-100'' and the parameter ''cases'' is set to the range ''50-150'', cases 50 to 100 are retrieved.
    * Setting the parameter to ''none'' deactivates data retrieval, for example if only variable information is of interest.
  * ''vList'' -- Variables to retrieve.
    * If the parameter ''vList'' is set, only (!) those variables will be retrieved.
    * Separate multiple variable labels with commas, e.g. ''CASE,AB01_01,AB01_02''.
    * The parameter ''vSkip'' is ignored if ''vList'' is set.
  * ''vSkip'' -- Skip single variables.
  * ''vSkipTime'' -- Skip dwell time (TIME000) and last data timestamp (LASTDATA) variables.
  * ''vQuality'' -- Add [[:en:results:variables#quality_indicators|quality indicators]] (MISSING, MISSREL, TIME_RSI, DEG_TIME).\\ **Warning:** Some of the quality indicators are normalized on the basis of the retrieved data. This may lead to missing or biased values if not all data is retrieved.
  * ''vAddress'' -- Add contact info of panel members (email, phone number, UID) (only possible if panel data was imported as [[:en:survey:mailing#privacy_mode|person-related data]]).
  * ''startMin'' -- Retrieve only cases that started the questionnaire after this date.
    * Excludes all cases that started the questionnaire before this data (variable: STARTED).
    * May be set in the formats YYYY-MM-DD or YYYY-MM-DD SS:MM:SS, e.g. ''2018-04-01T16:30:30'' ("T" may be replaced by a single space).
  * ''startMax'' -- Retrieve only cases that started the questionnaire until this date.
  * ''changed'' -- Retrieve only cases that changed some data after this date.
  * ''infoVariables'' -- Get additional variable information (e.g., scaling, input type).
  * ''infoValues'' -- Get value labels.
  * ''infoQuestionText'' -- Get question wording.

__Examples__:

Plain API link:

    https://www.soscisurvey.de/PROJEKT/?act=uDywDXaYyNEY

Retrieve only cases 120 and 121 and skip dwell time variables:

    https://www.soscisurvey.de/PROJEKT/?act=uDywDXaYyNEY&vSkipTime&cases=120,121

Retrieve only variables STARTED, AB01, AB02 and AB03_01 for cases that changed data after 2018-08-01 12:00:00:

    https://www.soscisurvey.de/PROJEKT/?act=uDywDXaYyNEY&vList=STARTED,AB01,AB02,AB03_01&changed=2018-08-01T12:00:00

Retrieve only variable labels:

    https://www.soscisurvey.de/PROJEKT/?act=uDywDXaYyNEY&cases=none&infoValues